<!DOCTYPE html>
<html lang="en-us">
  <head>

    <meta http-equiv="content-type" content="text/html; charset=utf-8">
    
<meta charset="UTF-8">
<title>Delete by query API | Elasticsearch Guide [7.7] | Elastic</title>
<link rel="home" href="index.html" title="Elasticsearch Guide [7.7]">
<link rel="up" href="docs.html" title="Document APIs">
<link rel="prev" href="docs-delete.html" title="Delete API">
<link rel="next" href="docs-update.html" title="Update API">
<meta name="DC.type" content="Learn/Docs/Elasticsearch/Reference/7.7">
<meta name="DC.subject" content="Elasticsearch">
<meta name="DC.identifier" content="7.7">
<meta name="robots" content="noindex,nofollow">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <script src="https://cdn.optimizely.com/js/18132920325.js"></script>
    <link rel="apple-touch-icon" sizes="57x57" href="/apple-icon-57x57.png">
    <link rel="apple-touch-icon" sizes="60x60" href="/apple-icon-60x60.png">
    <link rel="apple-touch-icon" sizes="72x72" href="/apple-icon-72x72.png">
    <link rel="apple-touch-icon" sizes="76x76" href="/apple-icon-76x76.png">
    <link rel="apple-touch-icon" sizes="114x114" href="/apple-icon-114x114.png">
    <link rel="apple-touch-icon" sizes="120x120" href="/apple-icon-120x120.png">
    <link rel="apple-touch-icon" sizes="144x144" href="/apple-icon-144x144.png">
    <link rel="apple-touch-icon" sizes="152x152" href="/apple-icon-152x152.png">
    <link rel="apple-touch-icon" sizes="180x180" href="/apple-icon-180x180.png">
    <link rel="icon" type="image/png" href="/favicon-32x32.png" sizes="32x32">
    <link rel="icon" type="image/png" href="/android-chrome-192x192.png" sizes="192x192">
    <link rel="icon" type="image/png" href="/favicon-96x96.png" sizes="96x96">
    <link rel="icon" type="image/png" href="/favicon-16x16.png" sizes="16x16">
    <link rel="manifest" href="/manifest.json">
    <meta name="apple-mobile-web-app-title" content="Elastic">
    <meta name="application-name" content="Elastic">
    <meta name="msapplication-TileColor" content="#ffffff">
    <meta name="msapplication-TileImage" content="/mstile-144x144.png">
    <meta name="theme-color" content="#ffffff">
    <meta name="naver-site-verification" content="936882c1853b701b3cef3721758d80535413dbfd">
    <meta name="yandex-verification" content="d8a47e95d0972434">
    <meta name="localized" content="true">
    <meta name="st:robots" content="follow,index">
    <meta property="og:image" content="https://www.elastic.co/static/images/elastic-logo-200.png">
    <link rel="shortcut icon" href="/favicon.ico" type="image/x-icon">
    <link rel="icon" href="/favicon.ico" type="image/x-icon">
    <link rel="apple-touch-icon-precomposed" sizes="64x64" href="/favicon_64x64_16bit.png">
    <link rel="apple-touch-icon-precomposed" sizes="32x32" href="/favicon_32x32.png">
    <link rel="apple-touch-icon-precomposed" sizes="16x16" href="/favicon_16x16.png">
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
    <link rel="stylesheet" type="text/css" href="/guide/static/styles.css">
  </head>

  <!--© 2015-2021 Elasticsearch B.V. Copying, publishing and/or distributing without written permission is strictly prohibited.-->

  <body>
    <!-- Google Tag Manager -->
    <script>dataLayer = [];</script><noscript><iframe src="//www.googletagmanager.com/ns.html?id=GTM-58RLH5" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
    <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start': new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0], j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src= '//www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f); })(window,document,'script','dataLayer','GTM-58RLH5');</script>
    <!-- End Google Tag Manager -->

    <!-- Global site tag (gtag.js) - Google Analytics -->
    <script async src="https://www.googletagmanager.com/gtag/js?id=UA-12395217-16"></script>
    <script>
      window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());
      gtag('config', 'UA-12395217-16');
    </script>

    <!--BEGIN QUALTRICS WEBSITE FEEDBACK SNIPPET-->
    <script type="text/javascript">
      (function(){var g=function(e,h,f,g){
      this.get=function(a){for(var a=a+"=",c=document.cookie.split(";"),b=0,e=c.length;b<e;b++){for(var d=c[b];" "==d.charAt(0);)d=d.substring(1,d.length);if(0==d.indexOf(a))return d.substring(a.length,d.length)}return null};
      this.set=function(a,c){var b="",b=new Date;b.setTime(b.getTime()+6048E5);b="; expires="+b.toGMTString();document.cookie=a+"="+c+b+"; path=/; "};
      this.check=function(){var a=this.get(f);if(a)a=a.split(":");else if(100!=e)"v"==h&&(e=Math.random()>=e/100?0:100),a=[h,e,0],this.set(f,a.join(":"));else return!0;var c=a[1];if(100==c)return!0;switch(a[0]){case "v":return!1;case "r":return c=a[2]%Math.floor(100/c),a[2]++,this.set(f,a.join(":")),!c}return!0};
      this.go=function(){if(this.check()){var a=document.createElement("script");a.type="text/javascript";a.src=g;document.body&&document.body.appendChild(a)}};
      this.start=function(){var a=this;window.addEventListener?window.addEventListener("load",function(){a.go()},!1):window.attachEvent&&window.attachEvent("onload",function(){a.go()})}};
      try{(new g(100,"r","QSI_S_ZN_emkP0oSe9Qrn7kF","https://znemkp0ose9qrn7kf-elastic.siteintercept.qualtrics.com/WRSiteInterceptEngine/?Q_ZID=ZN_emkP0oSe9Qrn7kF")).start()}catch(i){}})();
    </script><div id="ZN_emkP0oSe9Qrn7kF"><!--DO NOT REMOVE-CONTENTS PLACED HERE--></div>
    <!--END WEBSITE FEEDBACK SNIPPET-->

    <div id="elastic-nav" style="display:none;"></div>
    <script src="https://www.elastic.co/elastic-nav.js"></script>

    <!-- Subnav -->
    <div>
      <div>
        <div class="tertiary-nav d-none d-md-block">
          <div class="container">
            <div class="p-t-b-15 d-flex justify-content-between nav-container">
              <div class="breadcrum-wrapper"><span><a href="/guide/" style="font-size: 14px; font-weight: 600; color: #000;">Docs</a></span></div>
            </div>
          </div>
        </div>
      </div>
    </div>

    <div class="main-container">
      <section id="content">
        <div class="content-wrapper">

          <section id="guide" lang="en">
            <div class="container">
              <div class="row">
                <div class="col-xs-12 col-sm-8 col-md-8 guide-section">
                  <!-- start body -->
                  <div class="page_header">
<strong>IMPORTANT</strong>: No additional bug fixes or documentation updates
will be released for this version. For the latest information, see the
<a href="../current/index.html">current release documentation</a>.
</div>
<div id="content">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="index.html">Elasticsearch Guide [7.7]</a></span>
»
<span class="breadcrumb-link"><a href="rest-apis.html">REST APIs</a></span>
»
<span class="breadcrumb-link"><a href="docs.html">Document APIs</a></span>
»
<span class="breadcrumb-node">Delete by query API</span>
</div>
<div class="navheader">
<span class="prev">
<a href="docs-delete.html">« Delete API</a>
</span>
<span class="next">
<a href="docs-update.html">Update API »</a>
</span>
</div>
<div class="section">
<div class="titlepage"><div><div>
<h2 class="title">
<a id="docs-delete-by-query"></a>Delete by query API<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/docs/delete-by-query.asciidoc">edit</a>
</h2>
</div></div></div>

<p>Deletes documents that match the specified query.</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /twitter/_delete_by_query
{
  "query": {
    "match": {
      "message": "some message"
    }
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1477.console"></div>
<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="docs-delete-by-query-api-request"></a>Request<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/docs/delete-by-query.asciidoc">edit</a>
</h3>
</div></div></div>
<p><code class="literal">POST /&lt;index&gt;/_delete_by_query</code></p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="docs-delete-by-query-api-desc"></a>Description<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/docs/delete-by-query.asciidoc">edit</a>
</h3>
</div></div></div>
<p>You can specify the query criteria in the request URI or the request body
using the same syntax as the  <a class="xref" href="search-search.html" title="Search API">Search API</a>.</p>
<p>When you submit a delete by query request, Elasticsearch gets a snapshot of the index
when it begins processing the request and deletes matching documents using
<code class="literal">internal</code> versioning. If a document changes between the time that the
snapshot is taken and the delete operation is processed, it results in a version
conflict and the delete operation fails.</p>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>Documents with a version equal to 0 cannot be deleted using delete by
query because <code class="literal">internal</code> versioning does not support 0 as a valid
version number.</p>
</div>
</div>
<p>While processing a delete by query request, Elasticsearch performs multiple search
requests sequentially to find all of the matching documents to delete. A bulk
delete request is performed for each batch of matching documents. If a
search or bulk request is rejected, the requests are retried up to 10 times, with
exponential back off. If the maximum retry limit is reached, processing halts
and all failed requests are returned in the response. Any delete requests that
completed successfully still stick, they are not rolled back.</p>
<p>You can opt to count version conflicts instead of halting and returning by
setting <code class="literal">conflicts</code> to <code class="literal">proceed</code>.</p>
<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="_refreshing_shards"></a>Refreshing shards<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/docs/delete-by-query.asciidoc">edit</a>
</h4>
</div></div></div>
<p>Specifying the <code class="literal">refresh</code> parameter refreshes all shards involved in the delete
by query once the request completes. This is different than the delete API’s
<code class="literal">refresh</code> parameter, which causes just the shard that received the delete
request to be refreshed. Unlike the delete API, it does not support
<code class="literal">wait_for</code>.</p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="docs-delete-by-query-task-api"></a>Running delete by query asynchronously<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/docs/delete-by-query.asciidoc">edit</a>
</h4>
</div></div></div>
<p>If the request contains <code class="literal">wait_for_completion=false</code>, Elasticsearch
performs some preflight checks, launches the request, and returns a
<a class="xref" href="docs-delete-by-query.html#docs-delete-by-query-task-api" title="Running delete by query asynchronously"><code class="literal">task</code></a>
you can use to cancel or get the status of the task. Elasticsearch creates a
record of this task as a document at <code class="literal">.tasks/task/${taskId}</code>. When you are
done with a task, you should delete the task document so Elasticsearch can reclaim the
space.</p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="_waiting_for_active_shards"></a>Waiting for active shards<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/docs/delete-by-query.asciidoc">edit</a>
</h4>
</div></div></div>
<p><code class="literal">wait_for_active_shards</code> controls how many copies of a shard must be active
before proceeding with the request. See <a class="xref" href="docs-index_.html#index-wait-for-active-shards" title="Active shards">Active shards</a>
for details. <code class="literal">timeout</code> controls how long each write request waits for unavailable
shards to become available. Both work exactly the way they work in the
<a class="xref" href="docs-bulk.html" title="Bulk API">Bulk API</a>. Delete by query uses scrolled searches, so you can also
specify the <code class="literal">scroll</code> parameter to control how long it keeps the search context
alive, for example <code class="literal">?scroll=10m</code>. The default is 5 minutes.</p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="_throttling_delete_requests"></a>Throttling delete requests<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/docs/delete-by-query.asciidoc">edit</a>
</h4>
</div></div></div>
<p>To control the rate at which delete by query issues batches of delete operations,
you can set <code class="literal">requests_per_second</code> to any positive decimal number. This pads each
batch with a wait time to throttle the rate. Set <code class="literal">requests_per_second</code> to <code class="literal">-1</code>
to disable throttling.</p>
<p>Throttling uses a wait time between batches so that the internal scroll requests
can be given a timeout that takes the request padding into account. The padding
time is the difference between the batch size divided by the
<code class="literal">requests_per_second</code> and the time spent writing.  By default the batch size is
<code class="literal">1000</code>, so if <code class="literal">requests_per_second</code> is set to <code class="literal">500</code>:</p>
<div class="pre_wrapper lang-txt">
<pre class="programlisting prettyprint lang-txt">target_time = 1000 / 500 per second = 2 seconds
wait_time = target_time - write_time = 2 seconds - .5 seconds = 1.5 seconds</pre>
</div>
<p>Since the batch is issued as a single <code class="literal">_bulk</code> request, large batch sizes
cause Elasticsearch to create many requests and wait before starting the next set.
This is "bursty" instead of "smooth".</p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="docs-delete-by-query-slice"></a>Slicing<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/docs/delete-by-query.asciidoc">edit</a>
</h4>
</div></div></div>
<p>Delete by query supports <a class="xref" href="search-request-body.html#sliced-scroll" title="Sliced Scroll">sliced scroll</a> to parallelize the
delete process. This can improve efficiency and provide a
convenient way to break the request down into smaller parts.</p>
<p>Setting <code class="literal">slices</code> to <code class="literal">auto</code> chooses a reasonable number for most indices.
If you’re slicing manually or otherwise tuning automatic slicing, keep in mind
that:</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
Query performance is most efficient when the number of <code class="literal">slices</code> is equal to
the number of shards in the index. If that number is large (for example,
500), choose a lower number as too many <code class="literal">slices</code> hurts performance. Setting
<code class="literal">slices</code> higher than the number of shards generally does not improve efficiency
and adds overhead.
</li>
<li class="listitem">
Delete performance scales linearly across available resources with the
number of slices.
</li>
</ul>
</div>
<p>Whether query or delete performance dominates the runtime depends on the
documents being reindexed and cluster resources.</p>
</div>

</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="docs-delete-by-query-api-path-params"></a>Path parameters<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/docs/delete-by-query.asciidoc">edit</a>
</h3>
</div></div></div>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">&lt;index&gt;</code>
</span>
</dt>
<dd>
(Optional, string) A comma-separated list of index names to search. Use <code class="literal">_all</code>
or omit to search all indices.
</dd>
</dl>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="docs-delete-by-query-api-query-params"></a>Query parameters<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/docs/delete-by-query.asciidoc">edit</a>
</h3>
</div></div></div>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">allow_no_indices</code>
</span>
</dt>
<dd>
<p>
(Optional, boolean) If <code class="literal">true</code>,
the request does <span class="strong strong"><strong>not</strong></span> return an error
if a wildcard expression
or <code class="literal">_all</code> value retrieves only missing or closed indices.
</p>
<p>This parameter also applies to <a class="xref" href="indices-aliases.html" title="Update index alias API">index aliases</a>
that point to a missing or closed index.</p>
<p>Defaults to <code class="literal">true</code>.</p>
</dd>
<dt>
<span class="term">
<code class="literal">analyzer</code>
</span>
</dt>
<dd>
(Optional, string) Analyzer to use for the query string.
</dd>
<dt>
<span class="term">
<code class="literal">analyze_wildcard</code>
</span>
</dt>
<dd>
(Optional, boolean) If <code class="literal">true</code>, wildcard and prefix queries are
analyzed. Defaults to <code class="literal">false</code>.
</dd>
<dt>
<span class="term">
<code class="literal">conflicts</code>
</span>
</dt>
<dd>
(Optional, string) What to do if delete by query hits version conflicts:
<code class="literal">abort</code> or <code class="literal">proceed</code>. Defaults to <code class="literal">abort</code>.
</dd>
<dt>
<span class="term">
<code class="literal">default_operator</code>
</span>
</dt>
<dd>
(Optional, string) The default operator for query string query: AND or OR.
Defaults to <code class="literal">OR</code>.
</dd>
<dt>
<span class="term">
<code class="literal">df</code>
</span>
</dt>
<dd>
(Optional, string) Field to use as default where no field prefix is
given in the query string.
</dd>
<dt>
<span class="term">
<code class="literal">expand_wildcards</code>
</span>
</dt>
<dd>
<p>(Optional, string) Controls what kind of indices that wildcard expressions can
expand to. Multiple values are accepted when separated by a comma, as in
<code class="literal">open,hidden</code>. Valid values are:</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">all</code>
</span>
</dt>
<dd>
Expand to open and closed indices, including <a class="xref" href="index-modules.html#index-hidden">hidden indices</a>.
</dd>
<dt>
<span class="term">
<code class="literal">open</code>
</span>
</dt>
<dd>
Expand only to open indices.
</dd>
<dt>
<span class="term">
<code class="literal">closed</code>
</span>
</dt>
<dd>
Expand only to closed indices.
</dd>
<dt>
<span class="term">
<code class="literal">hidden</code>
</span>
</dt>
<dd>
Expansion of wildcards will include <a class="xref" href="index-modules.html#index-hidden">hidden indices</a>.
Must be combined with <code class="literal">open</code>, <code class="literal">closed</code>, or both.
</dd>
<dt>
<span class="term">
<code class="literal">none</code>
</span>
</dt>
<dd>
Wildcard expressions are not accepted.
</dd>
</dl>
</div>
<p>Defaults to <code class="literal">open</code>.</p>
</dd>
<dt>
<span class="term">
<code class="literal">from</code>
</span>
</dt>
<dd>
(Optional, integer) Starting document offset. Defaults to <code class="literal">0</code>.
</dd>
<dt>
<span class="term">
<code class="literal">ignore_unavailable</code>
</span>
</dt>
<dd>
(Optional, boolean) If <code class="literal">true</code>, missing or closed indices are not included in the
response. Defaults to <code class="literal">false</code>.
</dd>
<dt>
<span class="term">
<code class="literal">lenient</code>
</span>
</dt>
<dd>
(Optional, boolean) If <code class="literal">true</code>, format-based query failures (such as
providing text to a numeric field) will be ignored. Defaults to <code class="literal">false</code>.
</dd>
<dt>
<span class="term">
<code class="literal">max_docs</code>
</span>
</dt>
<dd>
(Optional, integer) Maximum number of documents to process. Defaults to all
documents.
</dd>
<dt>
<span class="term">
<code class="literal">preference</code>
</span>
</dt>
<dd>
(Optional, string) Specifies the node or shard the operation should be
performed on. Random by default.
</dd>
<dt>
<span class="term">
<code class="literal">q</code>
</span>
</dt>
<dd>
(Optional, string) Query in the Lucene query string syntax.
</dd>
<dt>
<span class="term">
<code class="literal">request_cache</code>
</span>
</dt>
<dd>
(Optional, boolean) If <code class="literal">true</code>, the request cache is used for this request.
Defaults to the index-level setting.
</dd>
<dt>
<span class="term">
<code class="literal">refresh</code>
</span>
</dt>
<dd>
(Optional, Boolean) If <code class="literal">true</code>, Elasticsearch refreshes all shards involved in the
delete by query after the request completes. Defaults to <code class="literal">false</code>.
</dd>
<dt>
<span class="term">
<code class="literal">requests_per_second</code>
</span>
</dt>
<dd>
(Optional, integer) The throttle for this request in sub-requests per second.
Defaults to <code class="literal">-1</code> (no throttle).
</dd>
<dt>
<span class="term">
<code class="literal">routing</code>
</span>
</dt>
<dd>
(Optional, string) Target the specified primary shard.
</dd>
<dt>
<span class="term">
<code class="literal">scroll</code>
</span>
</dt>
<dd>
(Optional, <a class="xref" href="common-options.html#time-units" title="Time units">time units</a>) Specifies how long a consistent view of
the index should be maintained for scrolled search.
</dd>
<dt>
<span class="term">
<code class="literal">scroll_size</code>
</span>
</dt>
<dd>
(Optional, integer) Size of the scroll request that powers the operation.
Defaults to 100.
</dd>
<dt>
<span class="term">
<code class="literal">search_type</code>
</span>
</dt>
<dd>
<p>
(Optional, string) The type of the search operation. Available options:
</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
<code class="literal">query_then_fetch</code>
</li>
<li class="listitem">
<code class="literal">dfs_query_then_fetch</code>
</li>
</ul>
</div>
</dd>
<dt>
<span class="term">
<code class="literal">timeout</code>
</span>
</dt>
<dd>
(Optional, <a class="xref" href="common-options.html#time-units" title="Time units">time units</a>)
Explicit timeout for each search request.
Defaults to no timeout.
</dd>
<dt>
<span class="term">
<code class="literal">slices</code>
</span>
</dt>
<dd>
(Optional, integer) The number of slices this task should be divided into.
Defaults to 1 meaning the task isn’t sliced into subtasks.
</dd>
<dt>
<span class="term">
<code class="literal">sort</code>
</span>
</dt>
<dd>
(Optional, string) A comma-separated list of &lt;field&gt;:&lt;direction&gt; pairs.
</dd>
<dt>
<span class="term">
<code class="literal">_source</code>
</span>
</dt>
<dd>
(Optional, string) True or false to return the <code class="literal">_source</code> field or not, or a
list of fields to return.
</dd>
<dt>
<span class="term">
<code class="literal">_source_excludes</code>
</span>
</dt>
<dd>
<p>
(Optional, string)
A comma-separated list of <a class="xref" href="mapping-source-field.html" title="_source field">source fields</a> to exclude from
the response.
</p>
<p>You can also use this parameter to exclude fields from the subset specified in
<code class="literal">_source_includes</code> query parameter.</p>
<p>If the <code class="literal">_source</code> parameter is <code class="literal">false</code>, this parameter is ignored.</p>
</dd>
<dt>
<span class="term">
<code class="literal">_source_includes</code>
</span>
</dt>
<dd>
<p>
(Optional, string)
A comma-separated list of <a class="xref" href="mapping-source-field.html" title="_source field">source fields</a> to
include in the response.
</p>
<p>If this parameter is specified, only these source fields are returned. You can
exclude fields from this subset using the <code class="literal">_source_excludes</code> query parameter.</p>
<p>If the <code class="literal">_source</code> parameter is <code class="literal">false</code>, this parameter is ignored.</p>
</dd>
<dt>
<span class="term">
<code class="literal">stats</code>
</span>
</dt>
<dd>
(Optional, string) Specific <code class="literal">tag</code> of the request for logging and statistical
purposes.
</dd>
<dt>
<span class="term">
<code class="literal">terminate_after</code>
</span>
</dt>
<dd>
(Optional, integer) The maximum number of documents to collect for each shard,
upon reaching which the query execution will terminate early.
</dd>
<dt>
<span class="term">
<code class="literal">master_timeout</code>
</span>
</dt>
<dd>
(Optional, <a class="xref" href="common-options.html#time-units" title="Time units">time units</a>) Specifies the period of time to wait for
a connection to the master node. If no response is received before the timeout
expires, the request fails and returns an error. Defaults to <code class="literal">30s</code>.
</dd>
<dt>
<span class="term">
<code class="literal">timeout</code>
</span>
</dt>
<dd>
(Optional, <a class="xref" href="common-options.html#time-units" title="Time units">time units</a>) Specifies the period of time to wait for
a response. If no response is received before the timeout expires, the request
fails and returns an error. Defaults to <code class="literal">30s</code>.
</dd>
<dt>
<span class="term">
<code class="literal">version</code>
</span>
</dt>
<dd>
(Optional, boolean) If <code class="literal">true</code>, returns the document version as part of a hit.
</dd>
<dt>
<span class="term">
<code class="literal">master_timeout</code>
</span>
</dt>
<dd>
(Optional, <a class="xref" href="common-options.html#time-units" title="Time units">time units</a>) Specifies the period of time to wait for
a connection to the master node. If no response is received before the timeout
expires, the request fails and returns an error. Defaults to <code class="literal">30s</code>.
</dd>
<dt>
<span class="term">
<code class="literal">timeout</code>
</span>
</dt>
<dd>
(Optional, <a class="xref" href="common-options.html#time-units" title="Time units">time units</a>) Specifies the period of time to wait for
a response. If no response is received before the timeout expires, the request
fails and returns an error. Defaults to <code class="literal">30s</code>.
</dd>
<dt>
<span class="term">
<code class="literal">wait_for_active_shards</code>
</span>
</dt>
<dd>
<p>(Optional, string) The number of shard copies that must be active before
proceeding with the operation. Set to <code class="literal">all</code> or any positive integer up
to the total number of shards in the index (<code class="literal">number_of_replicas+1</code>).
Default: 1, the primary shard.</p>
<p>See <a class="xref" href="docs-index_.html#index-wait-for-active-shards" title="Active shards">Active shards</a>.</p>
</dd>
</dl>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="docs-delete-by-query-api-request-body"></a>Request body<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/docs/delete-by-query.asciidoc">edit</a>
</h3>
</div></div></div>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">query</code>
</span>
</dt>
<dd>
(Optional, <a class="xref" href="query-dsl.html" title="Query DSL">query object</a>) Specifies the documents to delete
using the  <a class="xref" href="query-dsl.html" title="Query DSL">Query DSL</a>.
</dd>
</dl>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="docs-delete-by-quer-api-response-body"></a>Response body<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/docs/delete-by-query.asciidoc">edit</a>
</h3>
</div></div></div>
<p>The JSON response looks like this:</p>
<div class="pre_wrapper lang-console-result">
<pre class="programlisting prettyprint lang-console-result">{
  "took" : 147,
  "timed_out": false,
  "total": 119,
  "deleted": 119,
  "batches": 1,
  "version_conflicts": 0,
  "noops": 0,
  "retries": {
    "bulk": 0,
    "search": 0
  },
  "throttled_millis": 0,
  "requests_per_second": -1.0,
  "throttled_until_millis": 0,
  "failures" : [ ]
}</pre>
</div>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">took</code>
</span>
</dt>
<dd>
The number of milliseconds from start to end of the whole operation.
</dd>
<dt>
<span class="term">
<code class="literal">timed_out</code>
</span>
</dt>
<dd>
This flag is set to <code class="literal">true</code> if any of the requests executed during the
delete by query execution has timed out.
</dd>
<dt>
<span class="term">
<code class="literal">total</code>
</span>
</dt>
<dd>
The number of documents that were successfully processed.
</dd>
<dt>
<span class="term">
<code class="literal">deleted</code>
</span>
</dt>
<dd>
The number of documents that were successfully deleted.
</dd>
<dt>
<span class="term">
<code class="literal">batches</code>
</span>
</dt>
<dd>
The number of scroll responses pulled back by the delete by query.
</dd>
<dt>
<span class="term">
<code class="literal">version_conflicts</code>
</span>
</dt>
<dd>
The number of version conflicts that the delete by query hit.
</dd>
<dt>
<span class="term">
<code class="literal">noops</code>
</span>
</dt>
<dd>
This field is always equal to zero for delete by query. It only exists
so that delete by query, update by query, and reindex APIs return responses
 with the same structure.
</dd>
<dt>
<span class="term">
<code class="literal">retries</code>
</span>
</dt>
<dd>
The number of retries attempted by delete by query. <code class="literal">bulk</code> is the number
of bulk actions retried, and <code class="literal">search</code> is the number of search actions retried.
</dd>
<dt>
<span class="term">
<code class="literal">throttled_millis</code>
</span>
</dt>
<dd>
Number of milliseconds the request slept to conform to <code class="literal">requests_per_second</code>.
</dd>
<dt>
<span class="term">
<code class="literal">requests_per_second</code>
</span>
</dt>
<dd>
The number of requests per second effectively executed during the delete by query.
</dd>
<dt>
<span class="term">
<code class="literal">throttled_until_millis</code>
</span>
</dt>
<dd>
This field should always be equal to zero in a <code class="literal">_delete_by_query</code> response. It only
has meaning when using the <a class="xref" href="docs-delete-by-query.html#docs-delete-by-query-task-api" title="Running delete by query asynchronously">Task API</a>, where it
indicates the next time (in milliseconds since epoch) a throttled request will be
executed again in order to conform to <code class="literal">requests_per_second</code>.
</dd>
<dt>
<span class="term">
<code class="literal">failures</code>
</span>
</dt>
<dd>
Array of failures if there were any unrecoverable errors during the process. If
this is non-empty then the request aborted because of those failures.
Delete by query is implemented using batches, and any failure causes the entire
process to abort but all failures in the current batch are collected into the
array. You can use the <code class="literal">conflicts</code> option to prevent reindex from aborting on
version conflicts.
</dd>
</dl>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="docs-delete-by-query-api-example"></a>Examples<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/docs/delete-by-query.asciidoc">edit</a>
</h3>
</div></div></div>
<p>Delete all tweets from the <code class="literal">twitter</code> index:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST twitter/_delete_by_query?conflicts=proceed
{
  "query": {
    "match_all": {}
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1478.console"></div>
<p>Delete documents from multiple indices:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /twitter,blog/_delete_by_query
{
  "query": {
    "match_all": {}
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1479.console"></div>
<p>Limit the delete by query operation to shards that a particular routing
value:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST twitter/_delete_by_query?routing=1
{
  "query": {
    "range" : {
        "age" : {
           "gte" : 10
        }
    }
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1480.console"></div>
<p>By default <code class="literal">_delete_by_query</code> uses scroll batches of 1000. You can change the
batch size with the <code class="literal">scroll_size</code> URL parameter:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST twitter/_delete_by_query?scroll_size=5000
{
  "query": {
    "term": {
      "user": "kimchy"
    }
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1481.console"></div>
<h5>
<a id="docs-delete-by-query-manual-slice"></a>Slice manually<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/docs/delete-by-query.asciidoc">edit</a>
</h5>
<p>Slice a delete by query manually by providing a slice id and total number of
slices:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST twitter/_delete_by_query
{
  "slice": {
    "id": 0,
    "max": 2
  },
  "query": {
    "range": {
      "likes": {
        "lt": 10
      }
    }
  }
}
POST twitter/_delete_by_query
{
  "slice": {
    "id": 1,
    "max": 2
  },
  "query": {
    "range": {
      "likes": {
        "lt": 10
      }
    }
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1482.console"></div>
<p>Which you can verify works with:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET _refresh
POST twitter/_search?size=0&amp;filter_path=hits.total
{
  "query": {
    "range": {
      "likes": {
        "lt": 10
      }
    }
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1483.console"></div>
<p>Which results in a sensible <code class="literal">total</code> like this one:</p>
<div class="pre_wrapper lang-console-result">
<pre class="programlisting prettyprint lang-console-result">{
  "hits": {
    "total" : {
        "value": 0,
        "relation": "eq"
    }
  }
}</pre>
</div>
<h5>
<a id="docs-delete-by-query-automatic-slice"></a>Use automatic slicing<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/docs/delete-by-query.asciidoc">edit</a>
</h5>
<p>You can also let delete-by-query automatically parallelize using
<a class="xref" href="search-request-body.html#sliced-scroll" title="Sliced Scroll">sliced scroll</a> to slice on <code class="literal">_id</code>. Use <code class="literal">slices</code> to specify
the number of slices to use:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST twitter/_delete_by_query?refresh&amp;slices=5
{
  "query": {
    "range": {
      "likes": {
        "lt": 10
      }
    }
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1484.console"></div>
<p>Which you also can verify works with:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST twitter/_search?size=0&amp;filter_path=hits.total
{
  "query": {
    "range": {
      "likes": {
        "lt": 10
      }
    }
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1485.console"></div>
<p>Which results in a sensible <code class="literal">total</code> like this one:</p>
<div class="pre_wrapper lang-console-result">
<pre class="programlisting prettyprint lang-console-result">{
  "hits": {
    "total" : {
        "value": 0,
        "relation": "eq"
    }
  }
}</pre>
</div>
<p>Setting <code class="literal">slices</code> to <code class="literal">auto</code> will let Elasticsearch choose the number of slices
to use. This setting will use one slice per shard, up to a certain limit. If
there are multiple source indices, it will choose the number of slices based
on the index with the smallest number of shards.</p>
<p>Adding <code class="literal">slices</code> to <code class="literal">_delete_by_query</code> just automates the manual process used in
the section above, creating sub-requests which means it has some quirks:</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
You can see these requests in the
<a class="xref" href="docs-delete-by-query.html#docs-delete-by-query-task-api" title="Running delete by query asynchronously">Tasks APIs</a>. These sub-requests are "child"
tasks of the task for the request with <code class="literal">slices</code>.
</li>
<li class="listitem">
Fetching the status of the task for the request with <code class="literal">slices</code> only contains
the status of completed slices.
</li>
<li class="listitem">
These sub-requests are individually addressable for things like cancellation
and rethrottling.
</li>
<li class="listitem">
Rethrottling the request with <code class="literal">slices</code> will rethrottle the unfinished
sub-request proportionally.
</li>
<li class="listitem">
Canceling the request with <code class="literal">slices</code> will cancel each sub-request.
</li>
<li class="listitem">
Due to the nature of <code class="literal">slices</code> each sub-request won’t get a perfectly even
portion of the documents. All documents will be addressed, but some slices may
be larger than others. Expect larger slices to have a more even distribution.
</li>
<li class="listitem">
Parameters like <code class="literal">requests_per_second</code> and <code class="literal">max_docs</code> on a request with
slices` are distributed proportionally to each sub-request. Combine that with
the point above about distribution being uneven and you should conclude that
using <code class="literal">max_docs</code> with <code class="literal">slices</code> might not result in exactly <code class="literal">max_docs</code> documents
being deleted.
</li>
<li class="listitem">
Each sub-request gets a slightly different snapshot of the source index
though these are all taken at approximately the same time.
</li>
</ul>
</div>
<h5>
<a id="docs-delete-by-query-rethrottle"></a>Change throttling for a request<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/docs/delete-by-query.asciidoc">edit</a>
</h5>
<p>The value of <code class="literal">requests_per_second</code> can be changed on a running delete by query
using the <code class="literal">_rethrottle</code> API. Rethrottling that speeds up the
query takes effect immediately but rethrotting that slows down the query
takes effect after completing the current batch to prevent scroll
timeouts.</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST _delete_by_query/r1A2WoRbTwKZ516z6NEs5A:36619/_rethrottle?requests_per_second=-1</pre>
</div>
<div class="console_widget" data-snippet="snippets/1486.console"></div>
<p>Use the <a class="xref" href="tasks.html" title="Task management API">tasks API</a> to get the task ID. Set <code class="literal">requests_per_second</code>
to any positive decimal value or <code class="literal">-1</code> to disable throttling.</p>
<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="_get_the_status_of_a_delete_by_query_operation"></a>Get the status of a delete by query operation<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/docs/delete-by-query.asciidoc">edit</a>
</h4>
</div></div></div>
<p>Use the <a class="xref" href="tasks.html" title="Task management API">tasks API</a> to get the status of a delete by query
operation:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET _tasks?detailed=true&amp;actions=*/delete/byquery</pre>
</div>
<div class="console_widget" data-snippet="snippets/1487.console"></div>
<p>The response looks like:</p>
<div class="pre_wrapper lang-console-result">
<pre class="programlisting prettyprint lang-console-result">{
  "nodes" : {
    "r1A2WoRbTwKZ516z6NEs5A" : {
      "name" : "r1A2WoR",
      "transport_address" : "127.0.0.1:9300",
      "host" : "127.0.0.1",
      "ip" : "127.0.0.1:9300",
      "attributes" : {
        "testattr" : "test",
        "portsfile" : "true"
      },
      "tasks" : {
        "r1A2WoRbTwKZ516z6NEs5A:36619" : {
          "node" : "r1A2WoRbTwKZ516z6NEs5A",
          "id" : 36619,
          "type" : "transport",
          "action" : "indices:data/write/delete/byquery",
          "status" : {    <a id="CO554-1"></a><i class="conum" data-value="1"></i>
            "total" : 6154,
            "updated" : 0,
            "created" : 0,
            "deleted" : 3500,
            "batches" : 36,
            "version_conflicts" : 0,
            "noops" : 0,
            "retries": 0,
            "throttled_millis": 0
          },
          "description" : ""
        }
      }
    }
  }
}</pre>
</div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO554-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>This object contains the actual status. It is just like the response JSON
with the important addition of the <code class="literal">total</code> field. <code class="literal">total</code> is the total number
of operations that the reindex expects to perform. You can estimate the
progress by adding the <code class="literal">updated</code>, <code class="literal">created</code>, and <code class="literal">deleted</code> fields. The request
will finish when their sum is equal to the <code class="literal">total</code> field.</p>
</td>
</tr>
</table>
</div>
<p>With the task id you can look up the task directly:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET /_tasks/r1A2WoRbTwKZ516z6NEs5A:36619</pre>
</div>
<div class="console_widget" data-snippet="snippets/1488.console"></div>
<p>The advantage of this API is that it integrates with <code class="literal">wait_for_completion=false</code>
to transparently return the status of completed tasks. If the task is completed
and <code class="literal">wait_for_completion=false</code> was set on it then it’ll come back with
<code class="literal">results</code> or an <code class="literal">error</code> field. The cost of this feature is the document that
<code class="literal">wait_for_completion=false</code> creates at <code class="literal">.tasks/task/${taskId}</code>. It is up to
you to delete that document.</p>
<h4>
<a id="docs-delete-by-query-cancel-task-api"></a>Cancel a delete by query operation<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/docs/delete-by-query.asciidoc">edit</a>
</h4>
<p>Any delete by query can be canceled using the <a class="xref" href="tasks.html" title="Task management API">task cancel API</a>:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST _tasks/r1A2WoRbTwKZ516z6NEs5A:36619/_cancel</pre>
</div>
<div class="console_widget" data-snippet="snippets/1489.console"></div>
<p>The task ID can be found using the <a class="xref" href="tasks.html" title="Task management API">tasks API</a>.</p>
<p>Cancellation should happen quickly but might take a few seconds. The task status
API above will continue to list the delete by query task until this task checks that it
has been cancelled and terminates itself.</p>
</div>

</div>

</div>
<div class="navfooter">
<span class="prev">
<a href="docs-delete.html">« Delete API</a>
</span>
<span class="next">
<a href="docs-update.html">Update API »</a>
</span>
</div>
</div>

                  <!-- end body -->
                </div>
                <div class="col-xs-12 col-sm-4 col-md-4" id="right_col">
                  <div id="rtpcontainer" style="display: block;">
                    <div class="mktg-promo">
                      <h3>Most Popular</h3>
                      <ul class="icons">
                        <li class="icon-elasticsearch-white"><a href="https://www.elastic.co/webinars/getting-started-elasticsearch?baymax=default&amp;elektra=docs&amp;storm=top-video">Get Started with Elasticsearch: Video</a></li>
                        <li class="icon-kibana-white"><a href="https://www.elastic.co/webinars/getting-started-kibana?baymax=default&amp;elektra=docs&amp;storm=top-video">Intro to Kibana: Video</a></li>
                        <li class="icon-logstash-white"><a href="https://www.elastic.co/webinars/introduction-elk-stack?baymax=default&amp;elektra=docs&amp;storm=top-video">ELK for Logs &amp; Metrics: Video</a></li>
                      </ul>
                    </div>
                  </div>
                </div>
              </div>
            </div>
          </section>

        </div>


<div id="elastic-footer"></div>
<script src="https://www.elastic.co/elastic-footer.js"></script>
<!-- Footer Section end-->

      </section>
    </div>

<script src="/guide/static/jquery.js"></script>
<script type="text/javascript" src="/guide/static/docs.js"></script>
<script type="text/javascript">
  window.initial_state = {}</script>
  </body>
</html>
